Parent | Child | Previous | Next
 
JavaScript

A5.ListBoxsetValue Method

Syntax

A5.ListBox.setValue(target[,executeSelect])

A5.ListBox.setValue(customSelection[,executeSelect])

Arguments

targetany

The value(s) and or index(es) to use in the list. Pass in an array for values for multiple selections. See A5.ListBox.getIndex. Note: when using custom matching, only the first of the resulting indexes will be used.

customSelectionobject

Custom selection settings.

selectstring

The type of custom selection to do. Values are "all", "none", "add", "remove", "toggle", "match", "group" and "view". The "all" custom selection will select all values in the list. The "none" will deselect all values in the list. The "add", "remove" and "toggle" custom selections will perform those actions with the passed in value(s). The"match" custom selection will use a passed in function to match values to select. The "group" custom selection will select the given group(s) by name (the title of the group). The "view" custom selection selects all rows visible in the current view.

valueany

The value(s) to use in for "add", "remove" or "toggle". Pass in an array of values for multiple selections.

groupany

The group(s) to select for the "group" custom selection. Pass in an array of groups to select multiple groups.

matchfunction(value,data)

The function to use to match value(s) to be selected. This will be called for each value, and the function should return true or false to indicate if the value should be selected or not.

valueany

The value of a row in the list.

dataany

The data of a row in the list.

executeSelectboolean

Whether or not to execute the select events. The change event will always be executed when the value changes.

Description

Set the value in the list.

Example

// To get a pointer to the A5.ListBox class see {dialog.object}.getControl
// assume lObj is a pointer to an instance of the A5.ListBox class
lObj.setValue('a',true); // set the value of the view box to "a" and fire the select events
lObj.setValue(2,false); // select the 3rd item in the list but don't fire the select events
lObj.setValue({select: 'all'}); // select all
lObj.setValue({select: 'add', value: ['a','b']}); // add the values "a" and "b" to the current selection
lObj.setValue({select: 'match', match: function(v,d){
	if(d.company.toLowerCase() == 'alpha') return true;
	return false;
}}); // select rows with "alpha" as the company

In the case of List that uses client-side grouping, you can also select rows based on group names. For example, select all of the rows for records in the 'California' group.

Example: Setting the Value for a List Control in a UX Component

In the example below, the List value is set to 'ALFKI'.

var listObj = {dialog.object}.getControl('LIST1');
listObj.setValue('ALFKI');
The List's 'Return Value' property must be set to 'CustomerId' since 'ALFKI' is a CustomerId 'value'

When the value is set, the change event is fired. When the change event is fired, watch events are triggered. Watch events are created for calculated fields and show/hide events based on the value of the List, as well the logic that updates the dirty state for the List. You can also add your own watch events. To prevent the change event from executing, you can pass in an optional second parameter to setValue(). The second parameter defines whether or not the change event shoudl be fired. If false is passed in, the change event and subsequently watch events are not executed:

//Set value and do not fire the change event:
listObj.setValue('ALFKI',false);
You can also set the value of a List using the generic {dialog.object}.setValue() method. The .setValue() method for the List is convenient if you already have a pointer to the List control.

Example: Selecting Multiple Rows for a List Control in a UX Component

An object can be passed in instead of a single value to select rows in the List. This method can be used to select multiple rows in Lists with multi-selection enabled. For example, to select all rows, pass ina object with the property select set to 'all':

//Select all rows in a List (that has been configured to allows multiple selections)
var options = {};
options.select = 'all';
listObj.setValue(options);

The group option can be used to select rows that contain the same value. For example, you can select all rows with the valeu of 'CA' or 'MA' as follows:

//Select all rows in the 'CA' and 'MA' groups (de-selecting any existing rows)
var options = {};
options.select = 'group';
options.groups = ['CA','MA'];
options.additive = false;
listObj.setValue(options);

The additive property defines whether or not the matching rows should be added to the current selection. For example, the following will add all rows in the 'NY' group to the existing selected rows in the List:

//Select all rows in the 'NY' group (keeping any existing selections)
var options = {};
options.select = 'group';
options.groups = ['NY'];
options.additive = true;
listObj.setValue(options);

Example: Selecting Rows with List Virtualization

If List 'virtualization' is enabled for a List Control, you can select all of the rows on a current page of records as follows:

//In a List that has 'virtualization' turned on, select all rows in the current 'page' of records:
var options = {};
options.select = 'view';
options.additive = false;
listObj.setValue(options);

Example: Add Value to Current Selection for a List Control in a UX Component

The select: 'add' property can be usd to set the select row(s) in a List. If the List control is configured to allow multiple selection, the following code will select multiple rows:

// Select rows with a value of 'Smith' or 'Jones'
listObj.setValue({select: 'add', value : ['Smith','Jones']});

Example: Remove Value from Current Selection for a List Control in a UX Component

Rows in a List can be deselected by passing in the select: 'remove' option when using setValue(). For example, the following code will deselect multiple rows:

// Deselect rows with a value of 'Smith' or 'Jones'
listObj.setValue({select: 'remove', value: ['Smith','Jones']});

Example: Toggle Selected State of Items in the Value Array for a List Control in a UX Component

You can toggle the selected state of the specified rows using select: 'toggle'. For example, the following will toggle the selected state for the rows 'Smith' and 'Jones':

// Toggle the selected rows if they have a value of 'Smith' or 'Jones'
listObj.setValue({select: 'toggle', value: ['Smith','Jones']});

Example: Select Matching Rows for a List Control in a UX Component

If select: 'match' is specified, rows can be selected dynamically using a function. The function is specified with the match parameter. The value of the row and the data in the row will be passed to the function. The function must return a true or false value. If it returns true, the row will be selected. For example:

// Select rows that match the criteria specified by the function
var value = {};
value.select = 'match';
value.match = function(value, data) function(value,data) {
    //value and data for the current row
    if(data.Country == 'USA') return true;
    else return false;
};

listObj.setValue(value);

Example: Adding Rows to the Existing Selection for a List Control in a UX Component

The additive: true option will add the matching rows to the set of existing selected rows. For example:

// Add rows that match the criteria specified by the function
var value = {};
value.additive = true; // add matching rows to existing selected rows
value.select = 'match';
value.match = function(value, data) function(value,data) {
    //value and data for the current row
    if(data.Country == 'UK') return true;
    else return false;
};

listObj.setValue(value);

See Also